Game Music Box Manual

This is a beta release. See http://www.slack.net/~ant/game-music-box/dev.html for more.

Game Music Box plays Nintendo, Super Nintendo, Game Boy, Sega Genesis and Master System music files. It works with Mac OS X and Mac OS 9 (with CarbonLib 1.6 or later).

Contents:

- Game Music Files
- Playing Music
- Making Playlists
- Favorites Menu
- Playback Options
- Recording Tracks
- Music Utility
- Solving Problems
- Further Information
- Acknowledgements
- Sound Engine Details
- Legal
- Change Log

Game Music Files

The following music file formats are supported:

- Super Nintendo (SPC)
- Nintendo Entertainment System (NSF/NSFE)
- Nintendo Game Boy (GBS)
- Sega Master System (VGM, VGZ)
- Sega Genesis/Mega Drive (VGM, VGZ, GYM)

Video game music files can be found at the following web sites:

    http://www.2a03.org/
    http://www.snesmusic.org/
    http://slick.panicus.org/nsfe.php
    http://www.smspower.org/music/vgm/
    http://project2612.org/
    http://www.zophar.net/nsf/
    http://www.zophar.net/gbs/
    http://www.zophar.net/gym/
    
Most archives of game music files compressed with ZIP, GZIP, and RAR are supported transparently. For a summary of supported game music file formats and description of their characteristics, see the separate document Game Music Overview.

Playing Music

Drop music files or folders of music files on the Game Music Box application icon or double-click them to start playing them immediately and clear the previous playlist. Drop items on the player window to append them to end of the current playlist.

The player window shows information about the current track and allows skipping forward through the playlist or back through previous tracks. To reduce the window to just the track controls and track name, click the collapse button in the title bar.

The track control buttons and keyboard equivalents perform the following functions:

 Button  Keyboard      Function
--------------------------------------------------------------
    <<   Left Arrow    Previous track
   >/||  Spacebar      Play/Pause
    >>   Right Arrow   Next track (keep held for fast-forward)
 (none)  Esc or Cmd-.  Stop and clear playlist
             -         Lower volume
            +/=        Raise volume

To quickly change tracks, hold the left/right arrow key until it repeats. To fast-forward through the current track, use the mouse to press and hold the next track button.

The icon in the title bar of the player window is similar to that in Finder windows. Hold the command key while clicking the title to get a popup with the path of the current music file. Select the enclosing folder to reveal the current file in the Finder.

When the player window is in the background, track controls can still be used. In Mac OS X press and hold the mouse button over the Game Music Box application icon in the dock to bring up a menu with basic track controls, similar to that in Apple's iTunes.

There is currently no way to show a list of tracks in the current playlist.

Making Playlists

A playlist can be made by creating a new folder and putting into it aliases to the desired music files (aliases to other folders of music can also be included). To quickly make an alias, drag the item to the playlist folder while holding the command and option keys. To start a playlist, drop the folder on the player as described above.

Some music formats have multiple tracks in a single album file; to include a particular track in a playlist folder (rather than the whole album), rename the alias to have a pound sign ('#') and the track number after. For example, renaming an alias to Castlevania #9 plays only track 9.

Favorites Menu

The player keeps track of favorite tracks; to add the current track to the favorites, select Add To Favorites. The favorites menu currently only lists game systems and not individual favorites.

All favorites for a particular system or for the three "classic" systems (NES, Game Boy, Master System) can be added to the current playlist by using the Play All menu items. Choose Open Favorites to open the favorites folder in the Finder. Favorites are stored in folders suitable for use as playlists; just drop them on the player.

Playback Options

The Playback menu has track playback options:

Shuffle Tracks causes tracks to be played in random order from the playlist. The tracks from music albums are shuffled individually rather than as a single unit (applies to NSF, NSFE, GBS, and archives).

Skip Short Tracks causes short tracks to be skipped over, useful for eliminating sound effects and short tunes. Specifically, tracks with timing information (NSFE, VGM, GYM, most SPC) that are ten seconds or less. Tracks without timing information will not be skipped (NSF and GBS have no timing information at all).

Extend Current adds one minute to the play time of the just current track. This is useful if you are enjoying the current track and want to listen to it longer. This item is disabled for tracks which can't be extended (Sega Genesis and Master System tracks which have no loop points set).

Short, Normal, Extended, and Endless adjust the track play length. These change the time a track plays before it fades out, relative to the track's normal length (2.5 minutes if music file doesn't have timing information). The play length of the current track is shown in the main window. Note that some tracks can't be extended.

Show Sound Scope enables a sound oscilloscope that shows the sound waveform being played. It can be toggled between two sizes using the zoom box in the title bar.

Sound Channels in the Edit menu opens the channels window. In that window, Customize Sound is available for Nintendo, Game Boy and Master System music. When off, each system's unique sound quality is used; when on, the sliders override this with custom treble, bass, and stereo depth settings. Below that, individual channels can be muted to allow examination of how a song is constructed. Channels are muted only while the channels window is open.

Disable SNES Surround in the Preferences window disables the pseudo-surround effect used in some Super Nintendo soundtracks. It is especially useful when listening with headphones.

Recording Tracks

Tracks from music files can be recorded to wave sound files for conversion to mp3 or other format using another application (i.e. iTunes). The track length setting in the Playback menu sets the length of recorded tracks.

To record the current track in the player window, select Record Track from the File menu. If the channels window is open, muting will be applied to the track during conversion.

To record an entire playlist or multiple items, use the music utility.

Music Utility

A music utility is included for performing various actions on music files and archives. Items can be recorded to a folder, have their icons updated, be renamed, compressed or expanded, or checked for problems. Select Open Music Utility from the File menu to open the utility window.

Press Start to perform the selected action on game music files and archives in the list. If a folder is dropped, the actions are performed on all the items within the folder (and any nested folders), except as noted. Errors that occur during processing are listed afterwards.

Record To Folder

Records items (including aliases and nested folders) to a folder. Custom sound settings from the sound channels window are applied during recording (except channel muting). If a recording already exists in the destination folder, that track is skipped; to re-record a track, choose a different destination folder or manually delete the recording first.

Update Icons

Updates each file's icon and sets it to open with Game Music Box. It can optionally hide (OS X) or remove (OS 9) the filename extension ("Castlevania.nsf" becomes "Castlevania"). In OS X this doesn't always change the icon (the issue is being investigated).

Rename Files From Tags

Renames individual music files and archives using any available information fields from within the files. It will attempt to preserve track numbers, but this is tricky due to the lack of a consistent naming standard. Since this is a significant operation, it is performed only on the immediate items in any folders dropped (nested folders are skipped).

Compress Files

Compresses individual files with gzip, which is widely supported by game music players. Skips archives.

Expand Files

Expands individual files previously compressed with gzip. Skips archives.

Check For Problems

Checks each track of music files and each file in archives for corruption, and for compatibility with the player. Also checks for unresolved aliases. This is useful for finding any problems with a playlist, since normal playing skips over errors.

Solving Problems

Update File Icon When Played in the preferences window changes the icon of files as they are played (if the icon is not already correct). It is useful when a downloaded music file doesn't have the proper icon. Use the music utility if this isn't sufficient.

If you're having trouble with a game music file or archive, drop it alone on the Game Music Box application icon to perform extra checking and report why it won't play. One limitation is that archives must contain music from only one system (manually expand the archive if it contains music for multiple systems).

If tracks seem to be playing in an unexpected order, be sure that Shuffle and Skip Short Tracks in the Playback menu aren't checked.

Currently some RAR archives (those with solid compression) require over 30 megabytes of free memory when reading from them. Changing tracks within them might also be slow, especially when going to the previous track or using RAR archives of large GYM files. If this is a problem, expand the RAR archive with a decompression utility first.

Some GYM soundtracks use internal compression that Game Music Box doesn't support. Attempt to play these will give an error. It might be possible to find an uncompressed version.

Further Information

If you encounter any problems, please report what happened and what music you were playing at the time (and preferably what site you downloaded it from). If running Mac OS X, include a copy of the crash log if possible. See the development section of the web site for a list of known problems.

Join the discussion group to post questions, ideas, and bug reports:

    http://groups-beta.google.com/group/game-music-box

Visit the home page for the latest version, development progress, and C++ source code:

    http://www.slack.net/~ant/game-music-box

Acknowledgements

Thanks to Alexander Strange, Mark Laws, and Mute for testing and feedback. Thanks to Kode54, Richard Bannister, and Mahendra Tallur for testing and feedback on the sound engine (Game_Music_Emu).

Sound Engine Details

Emulation is handled by the open-source library Game_Music_Emu.

Sega Genesis GYM files are played using an enhanced decoder which compensates somewhat for the GYM format's poor representation of samples. Super Nintendo SPC files are emulated at 32kHz as closely as possible to SNES hardware, then resampled to the output rate. The one "enhancement" is removal of the annoying pseudo-surround some games add using inverted left/right phases. The stereo sound slider pans the first two channels from the center to the left and right and adds reverb to them, and adds echo to the other channels. Whenever sound is paused, stopped, resumed, or skipped, a very short fade is used to prevent clicking (channel muting does click).

Up to 20 seconds of silence are skipped at the beginning of a track before treating it as a non-playable track (Game Boy, Zelda: Link's Awakening, track 61). Tracks without timing information are automatically ended when six seconds of silence are encountered (Game Boy, Metroid 2, track 6). When the channels window is open, automatic silence skipping is disabled and sound latency is lowered to provide immediate feedback of changes to muting and sound customization.

Legal

Game Music Box is copyright (C) 2005-2006 by Shay Green. It may be distributed and used free of charge, but may not be sold.

Game Music Box uses Game_Music_Emu for sound synthesis, licensed under the GNU Lesser General Public License (LGPL). Copyright (C) 2003-2006 Shay Green. SNES SPC DSP emulator based on OpenSPC, Copyright (C) 2002 Brad Martin. Sega Genesis YM2612 emulator from Gens project, Copyright (C) 2002 Stephane Dallongeville.

Unrar copyright Alexander Roshal. The unRAR sources may be used in any software to handle RAR archives without limitations free of charge, but cannot be used to re-create the RAR compression algorithm, which is proprietary. Distribution of modified unRAR sources in separate form or as a part of other software is permitted, provided that it is clearly stated in the documentation and source comments that the code may not be used to develop a RAR (WinRAR) compatible archiver.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Change Log

Version 0.5.2
- Added support for Sega Genesis/Mega Drive VGMs using the new smaller format
- Added support for Sunsoft FME-7 sound, allowing the Gimmick NSF soundtrack to play
- Added SPC surround sound disable checkbox to preferences
- Made several minor fixes for some soundtracks

- Shay Green <hotpop.com@blargg> (swap to e-mail)
